function lst = reserve(lst, capacity)
%RESERVE Reserves the capacity of the list
%
% [ Syntax ]
%   - lst = reserve(lst, capacity)
%
% [ Description ]
%   - lst = reserve(lst, capacity) reserves the capacity of the list to
%     the input value. 
%
% [ Remarks ]
%   - The input capacity should not be less than the length of the list.
%
% [ History ]
%  - Created by Dahua Lin, on Jan 5, 2008
%

%% parse and verify input 
 
 assert(capacity >= length(lst), ...
     'sltoolbox:sllist:reserve:invalidarg', ...
     'The input capacity for reserve should >= the length of the list.');
 
%% main

cc = length(lst.items);

if capacity > cc
    lst.items = [lst.items; cell(capacity - cc, 1)];
    
elseif capacity < cc
    lst.items(capacity + 1 : cc) = [];
    
end

